feat(agent-spec): simplify resource references - #307
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 363805c80c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Rebased onto No semantic changes: the rebase is clean (disjoint surfaces — agent-spec/crates vs event.rs/ding). Verified at a1931fb: Linux x86_64 Downstream note for schickling/dotfiles#1898: once this merges, one forward bump carries both the resource-reference envelope and the darwin fix. |
363805c to
a1931fb
Compare
|
macOS arm64 full-suite result at a1931fb: |
…rations and docs Codex review (P1): requiring reason invalidated the repository's own examples — validate.rs/status_agents.rs fixtures parse-errored into empty rosters, and README/vrs spec still documented a name+uri-only envelope. Add reason to every bundled declaration and update the contract prose to name+uri+reason with optional inactive-reason.
Codex review (P2): normalize_agent projected only /resources/<name>/uri, so edits touching just reason or inactive-reason produced a modified-file marker with no agent semantic field. Emit /reason and optional /inactive-reason alongside /uri so diff consumers can observe explanation and active-state changes.
1 participant
Summary
reasonmandatory on every Agent Spec Resource referencerelationfieldinactive-reasonso append-mostly Agent Specs can retain references that are no longer active for that agentMotivation
Agent Specs are becoming the passive coordination index for agent workstreams. A local label is useful to the reading agent, while the URI carries the actual resource type and identity. The generic
relationfield duplicated the label/reason without establishing useful semantics.Long-lived specs also need to retain historical references for traceability without implying that every referenced PR, worktree, or worklog remains current.
inactive-reasonexpresses only that the reference is inactive in this Agent Spec; it does not alter the resource's lifecycle, authority, or resolution.The resulting envelope stays intentionally small:
Verification
cargo test -p agent-spec- PASS (68 tests across unit/integration targets)cargo test --all-targets --all-features- Resource/parser changes PASS; one unrelated runtime test,incomplete_apply_marker_blocks_declarations_but_not_the_state_plane, is RED locally and was not modified by this PRcargo fmt --all -- --check- PASS